home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kdatatool.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  10.5 KB  |  302 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 1998, 1999, 2000 Torben Weis <weis@kde.org>
  3.    Copyright (C) 2001 David Faure <david@mandrakesoft.com>
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License as published by the Free Software Foundation; either
  8.    version 2 of the License, or (at your option) any later version.
  9.  
  10.    This library is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.    Library General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU Library General Public License
  16.    along with this library; see the file COPYING.LIB.  If not, write to
  17.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.    Boston, MA 02110-1301, USA.
  19. */
  20.  
  21. #ifndef KDATATOOL_H
  22. #define KDATATOOL_H
  23.  
  24. #include <qobject.h>
  25. #include <qvaluelist.h>
  26.  
  27. #include <kaction.h>
  28. #include <kservice.h>
  29.  
  30. class KDataTool;
  31. class QPixmap;
  32. class QStringList;
  33. class KInstance;
  34.  
  35. // If you're only looking at implementing a data-tool, skip directly to the last
  36. // class definition, KDataTool.
  37.  
  38. /**
  39.  * This is a convenience class for KService. You can use it if you have
  40.  * a KService describing a KDataTool. In this case the KDataToolInfo class
  41.  * is more convenient to work with.
  42.  *
  43.  * Especially useful is the method createTool which creates the datatool
  44.  * described by the service.
  45.  * @see KDataTool
  46.  */
  47. class KIO_EXPORT KDataToolInfo
  48. {
  49. public:
  50.     /**
  51.      * Create an invalid KDataToolInfo.
  52.      */
  53.     KDataToolInfo();
  54.     /**
  55.      * Create a valid KDataToolInfo.
  56.      * @param service the corresponding service
  57.      * @param instance the instance to use
  58.      */
  59.     KDataToolInfo( const KService::Ptr& service, KInstance* instance );
  60.     /**
  61.      * Copy constructor.
  62.      */
  63.     KDataToolInfo( const KDataToolInfo& info );
  64.     /**
  65.      * Assignment operator.
  66.      */
  67.     KDataToolInfo& operator= ( const KDataToolInfo& info );
  68.  
  69.     /**
  70.      * Returns the data type that the DataTool can accept.
  71.      * @return the C++ data type that this DataTool accepts.
  72.      *         For example "QString" or "QImage" or something more
  73.      *         complicated.
  74.      */
  75.     QString dataType() const;
  76.     /**
  77.      * Returns a list of mime type that will be accepted by the DataTool.
  78.      * The mimetypes are only used if the dataType can be used to store
  79.      * different mimetypes. For example in a "QString" you could save "text/plain"
  80.      * or "text/html" or "text/xml".
  81.      *
  82.      * @return the mime types accepted by this DataTool. For example
  83.      *         "image/gif" or "text/plain". In some cases the dataType
  84.      *         determines the accepted type of data perfectly. In this cases
  85.      *         this list may be empty.
  86.      */
  87.     QStringList mimeTypes() const;
  88.  
  89.     /**
  90.      * Checks whether the DataTool is read-only.
  91.      * @return true if the DataTool does not modify the data passed to it by KDataTool::run.
  92.      */
  93.     bool isReadOnly() const;
  94.  
  95.     /**
  96.      * Returns the icon of this data tool.
  97.      * @return a large pixmap for the DataTool.
  98.      * @deprecated, use iconName()
  99.      */
  100.     QPixmap icon() const KDE_DEPRECATED;
  101.     /**
  102.      * Returns the mini icon of this data tool.
  103.      * @return a mini pixmap for the DataTool.
  104.      * @deprecated, use iconName()
  105.      */
  106.     QPixmap miniIcon() const KDE_DEPRECATED;
  107.     /**
  108.      * Returns the icon name for this DataTool.
  109.      * @return the name of the icon for the DataTool
  110.      */
  111.     QString iconName() const;
  112.     /**
  113.      * Returns a list of strings that you can put in a QPopupMenu item, for example to
  114.      * offer the DataTools services to the user. The returned value
  115.      * is usually something like "Spell checking", "Shrink Image", "Rotate Image"
  116.      * or something like that.     
  117.      * This list comes from the Comment field of the tool's desktop file
  118.      * (so that it can be translated).
  119.      *
  120.      * Each of the strings returned corresponds to a string in the list returned by
  121.      * commands.
  122.      *
  123.      * @return a list of strings that you can put in a QPopupMenu item
  124.      */
  125.     QStringList userCommands() const;
  126.     /**
  127.      * Returns the list of commands the DataTool can execute. The application
  128.      * passes the command to the KDataTool::run method.
  129.      *
  130.      * This list comes from the Commands field of the tool's desktop file.
  131.      *
  132.      * Each of the strings returned corresponds to a string in the list returned by
  133.      * userCommands.
  134.      * @return the list of commands the DataTool can execute, suitable for 
  135.      *         the KDataTool::run method.
  136.      */
  137.     QStringList commands() const;
  138.  
  139.     /**
  140.      * Creates the data tool described by this KDataToolInfo.
  141.      * @param parent the parent of the QObject (or 0 for parent-less KDataTools)
  142.      * @param name the name of the QObject, can be 0
  143.      * @return a pointer to the created data tool or 0 on error.
  144.      */
  145.     KDataTool* createTool( QObject* parent = 0, const char* name = 0 ) const;
  146.  
  147.     /**
  148.      * The KDataToolInfo's service that is represented by this class.
  149.      * @return the service
  150.      */
  151.     KService::Ptr service() const;
  152.  
  153.     /**
  154.      * The instance of the service.
  155.      * @return the instance
  156.      */
  157.     KInstance* instance() const { return m_instance; }
  158.  
  159.     /**
  160.      * A DataToolInfo may be invalid if the KService passed to its constructor does
  161.      * not feature the service type "KDataTool".
  162.      * @return true if valid, false otherwise
  163.      */
  164.     bool isValid() const;
  165.  
  166.     /**
  167.      * Queries the KTrader about installed KDataTool implementations.
  168.      * @param datatype a type that the application can 'export' to the tools (e.g. QString)
  169.      * @param mimetype the mimetype of the data (e.g. text/plain)
  170.      * @param instance the application (or the part)'s instance (to check if a tool is excluded from this part,
  171.      * and also used if the tool wants to read its configuration in the app's config file).
  172.      * @return the list of results
  173.      */
  174.     static QValueList<KDataToolInfo> query( const QString& datatype, const QString& mimetype, KInstance * instance );
  175.  
  176. private:
  177.     KService::Ptr m_service;
  178.     KInstance* m_instance;
  179. private:
  180.     class KDataToolInfoPrivate* d;
  181. };
  182.  
  183.  
  184. /**
  185.  * This class helps applications implement support for KDataTool.
  186.  * The steps to follow are simple:
  187.  * @li query for the available tools using KDataToolInfo::query
  188.  * @li pass the result to KDataToolAction::dataToolActionList (with a slot)
  189.  * @li plug the resulting actions, either using KXMLGUIClient::plugActionList, or by hand.
  190.  *
  191.  * The slot defined for step 2 is called when the action is activated, and
  192.  * that's where the tool should be created and run.
  193.  */
  194. class KIO_EXPORT KDataToolAction : public KAction
  195. {
  196.     Q_OBJECT
  197. public:
  198.     /**
  199.      * Constructs a new KDataToolAction.
  200.      *
  201.      * @param text The text that will be displayed.
  202.      * @param info the corresponding KDataToolInfo
  203.      * @param command the command of the action
  204.      * @param parent This action's parent.
  205.      * @param name An internal name for this action.
  206.      */
  207.     KDataToolAction( const QString & text, const KDataToolInfo & info, const QString & command, QObject * parent = 0, const char * name = 0);
  208.  
  209.     /**
  210.      * Creates a list of actions from a list of information about data-tools.
  211.      * The slot must have a signature corresponding to the toolActivated signal.
  212.      *
  213.      * Note that it's the caller's responsibility to delete the actions when they're not needed anymore.
  214.      * @param tools the list of data tool descriptions
  215.      * @param receiver the receiver for toolActivated() signals
  216.      * @param slot the slot that will receive the toolActivated() signals
  217.      * @return the KActions
  218.      */
  219.     static QPtrList<KAction> dataToolActionList( const QValueList<KDataToolInfo> & tools, const QObject *receiver, const char* slot );
  220.  
  221. signals:
  222.     /**
  223.      * Emitted when a tool has been activated.
  224.      * @param info a description of the activated tools
  225.      * @param command the command for the tool
  226.      */
  227.     void toolActivated( const KDataToolInfo & info, const QString & command );
  228.  
  229. protected:
  230.     virtual void slotActivated();
  231.  
  232. private:
  233.     QString m_command;
  234.     KDataToolInfo m_info;
  235. protected:
  236.     virtual void virtual_hook( int id, void* data );
  237. private:
  238.     class KDataToolActionPrivate* d;
  239.  
  240. };
  241.  
  242. /**
  243.  * A generic tool that processes data.
  244.  *
  245.  * A data-tool is a "plugin" for an application, that acts (reads/modifies)
  246.  * on a portion of the data present in the document (e.g. a text document,
  247.  * a single word or paragraph, a KSpread cell, an image, etc.)
  248.  *
  249.  * The application has some generic code for presenting the tools in a popupmenu
  250.  * @see KDataToolAction, and for activating a tool, passing it the data
  251.  * (and possibly getting modified data from it).
  252.  */
  253. class KIO_EXPORT KDataTool : public QObject
  254. {
  255.     Q_OBJECT
  256. public:
  257.     /**
  258.      * Constructor
  259.      * The data-tool is only created when a menu-item, that relates to it, is activated.
  260.      * @param parent the parent of the QObject (or 0 for parent-less KDataTools)
  261.      * @param name the name of the QObject, can be 0
  262.      */
  263.     KDataTool( QObject* parent = 0, const char* name = 0 );
  264.  
  265.     /**
  266.      * @internal. Do not use under any circumstance (including bad weather).
  267.      */
  268.     void setInstance( KInstance* instance ) { m_instance = instance; }
  269.  
  270.     /**
  271.      * Returns the instance of the part that created this tool.
  272.      * Usually used if the tool wants to read its configuration in the app's config file.
  273.      * @return the instance of the part that created this tool.
  274.      */
  275.     KInstance* instance() const;
  276.  
  277.     /**
  278.      * Interface for 'running' this tool.
  279.      * This is the method that the data-tool must implement.
  280.      *
  281.      * @param command is the command that was selected (see KDataToolInfo::commands())
  282.      * @param data the data provided by the application, on which to run the tool.
  283.      *             The application is responsible for setting that data before running the tool,
  284.      *             and for getting it back and updating itself with it, after the tool ran.
  285.      * @param datatype defines the type of @p data.
  286.      * @param mimetype defines the mimetype of the data (for instance datatype may be
  287.      *                 QString, but the mimetype can be text/plain, text/html etc.)
  288.      * @return true if successful, false otherwise
  289.      */
  290.     virtual bool run( const QString& command, void* data, const QString& datatype, const QString& mimetype) = 0;
  291.  
  292. private:
  293.     KInstance * m_instance;
  294. protected:
  295.     virtual void virtual_hook( int id, void* data );
  296. private:
  297.     class KDataToolPrivate;
  298.     KDataToolPrivate * d;
  299. };
  300.  
  301. #endif
  302.